Xab Version 0.1

Requirements: X11R5 and PVM

Overview

Xab is a set of tools which provide for the visual (X based) analysis
and debugging of PVM programs.  The basic idea behind Xab is to
instrument every PVM call so it sends a message to a monitoring process
which can either display the event or save it in file for later
analysis.  


The major components fo Xab are as follows:

abmon:  abmon is a PVM program which will read monitor messages and save
them to a file or standard out.

xab: this program will display xab events as they arrive.  They may
either be read from standard in or from a file.

libf2x.a: this is the library which must be used for FORTRAN programs
instead of libf2c.a

libab.a:  this library must be linked to any programs to be monitored.

topg: this shell script uses an awk script to convert the output of
abmon into picl trace format.


To use xab you need to do the following:
	o include "xab.h" in your pvm C source files and recompile
	  (for fortran simply link to libf2x.a, no need to mess with
	  include files or recompile)
	o link your pvm executables to libab.a (and libf2x.a for fortran)
	o run abmon on some host in your virtual machine
	o run your program

To run abmon type:
	% abmon <file> 

The abmon program will enroll("xab") and write trace events to the
file you give it on the command line.  Stdout is the default file
is one is not given.

Abmon must start before any other program to be monitored.

Abmon will exit after all the processes it's monitoring have
exited via leave();

Abmon trace events are not very pretty but they are generally
human readable.  The first time stamp for an event is from the originating
processor.  The last time stamp on an event is from local abmon processor.

To run abmon and xab type:
	% abmon | xab
The abmon program will flush after every event if the output is going to 
standard out so the xab program will show the latest events.

Or if you want to keep the trace events around:
	% abmon | tee xabevfile | xab
Since tee may not flush its stdio the xab display may be out of sync.

If you want to look at the output in Paragraph type:
	% topg <fn>
and this will create a file fn.trf which you can then use
in Paragraph.  Because paragraph makes the assumption that
there is only one process per node, topg maps components to
nodes.  

For this to make sense one must assume the clocks of the machines
are synced.  If you are running ntp then things may be ok.  There
is no effort to sync clocks.

COMPILING

To make the files libab.a and abmon simply change to the directory
where for the appropriate architecture (ie pvm/xab/PMAX) and type 
make.  You may need to set the variables ARCH and PVMLIB in the makefile:

ARCH=	PMAX
PVMLIB=	$(HOME)/pvm/src/$(ARCH)/libpvm.a

Do the same for libf2x.a but cd to ~/pvm/f2x/ARCH.

To make xab cd to ~/pvm/xab then type 
	% xmkmf
	% make


FUTURE

I plan on makeing this tool more comprehensive.  I would like to 
expand the diagnostics of xab.  It should catch things like
puts and gets that don't match.  It should also try to do some
sort of timing feedback.

If you have any trouble, comments or suggestions, please send me email.

	Adam


Adam Beguelin				Carnegie Mellon University 
adamb@cs.cmu.edu			School of Computer Science
Faculty, RCS				5000 Forbes Avenue
(412)268-5295				Pittsburgh, PA 15213-3890
